fix(sentry): stop reporting optional-integration import errors as SDK bugs#175
Conversation
…YTHON-YY) The SDK's lightweight Sentry trace function reported ModuleNotFoundError exceptions raised while importing optional framework integrations (blaxel.openai, blaxel.livekit, ...) as if they were SDK bugs. These failures are environment issues: the user imported an integration without installing its extra, the extra has a missing transitive dependency, or a stripped/partial install is missing the integration's modules (e.g. 'No module named blaxel.openai.model'). Expand _is_optional_dependency_error to recognize: - import errors for any optional blaxel integration subpackage - import failures of third-party deps raised while loading an optional integration package Genuine SDK import bugs (failures on blaxel.* core modules) are still captured. Adds tests/core/test_sentry.py. Co-authored-by: psinai <psinai@blaxel.ai>
🧪 Testing GuideWhat this PR addressesThe SDK's global Steps to reproduce the original issue
What to verify (expected behavior)
Note Posted by PR Testing Guide · Tag @mendral-app with feedback. |
![mendral-app[bot]](https://avatars.githubusercontent.com/in/1975249?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
🔀 Interaction Flow DiagramHere's a sequence diagram showing how the updated Sentry error filtering pipeline processes import errors after this PR: sequenceDiagram
participant User as User Code
participant Init as blaxel.{integration}/__init__.py
participant Hook as sys.settrace Hook
participant Filter as _is_optional_dependency_error()
participant L1 as Level 1: Entrypoint Check
participant L2 as Level 2: 3rd-party Deps
participant L3 as Level 3: __cause__ Chain
participant L4 as Level 4: Integration Frame
participant Sentry as Sentry
User->>Init: import blaxel.openai
Init->>Init: from .model import * (missing extra)
Init-->>Hook: ModuleNotFoundError raised
Hook->>Filter: _is_optional_dependency_error(exc)
Filter->>L1: _is_optional_integration_entrypoint_missing()
Note right of L1: Check module name against<br/>_OPTIONAL_INTEGRATION_PACKAGES<br/>& _ENTRYPOINT_MODULES
alt Module is known optional entrypoint
L1-->>Filter: True
Filter-->>Hook: Suppress (not reported)
else Not a direct entrypoint
Filter->>L2: Check _OPTIONAL_DEPENDENCIES list
alt Known optional dep (e.g. opentelemetry)
L2-->>Filter: True
Filter-->>Hook: Suppress
else Unknown dependency
Filter->>L3: Walk exc.__cause__ chain (cycle-safe)
alt Wrapped ImportError from integration guard
L3-->>Filter: True
Filter-->>Hook: Suppress
else No matching cause
Filter->>L4: _has_optional_integration_frame()
Note right of L4: Walk traceback for<br/>integration directory paths
alt 3rd-party import inside integration frame
L4-->>Filter: True
Filter-->>Hook: Suppress
else Core SDK or unknown origin
L4-->>Filter: False
Filter-->>Hook: Report as SDK bug
Hook->>Sentry: Send event
end
end
end
end
SummaryThis PR introduces a 4-level hierarchical filter in the Sentry error hook to prevent optional-integration
Genuine SDK bugs (e.g., core Note Posted by PR Sequence Diagram · Tag @mendral-app with feedback. |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
LGTM
The refinement from broad startswith matching to an explicit entrypoint allowlist is a good tightening of the filter. Logic is correct, cycle detection is preserved, and the new test (test_missing_nested_blaxel_module_inside_integration_is_not_optional) validates the key behavioral change. No new correctness or security concerns.
Tag @mendral-app with feedback or questions. View session
2 participants
Problem
Sentry issue SDK-PYTHON-YY —
ModuleNotFoundError: No module named 'blaxel.livekit.model'(clustered withNo module named 'blaxel.openai.model'), 7 occurrences, 0 users impacted, releasesdk-python@0.2.58.Root cause
The SDK installs a global
sys.settracehook (src/blaxel/core/common/sentry.py) that forwards any exception whose frame lives insite-packages/blaxelto Blaxel's Sentry. Its_is_optional_dependency_errorallow-list only knew aboutopentelemetry.When a user imports an optional framework integration (
blaxel.openai,blaxel.livekit, …) in an environment that is missing the matching extra — or runs a stripped/partial install where the integration'smodel.pyis absent (common in.pyenv-based agent images, which is the exact production case: culpritblaxel/<pkg>/__init__.pyline 3 =from .model import *) — the resultingModuleNotFoundErrorwas captured and reported as if it were an SDK defect. These are environment issues, not SDK bugs.I verified this empirically:
0.2.58wheel and sdist both containmodel.pyfor every integration (so it is not a packaging bug).blaxel/openai/model.pyfrom a clean install reproduces the exact Sentry signature, includingexc.name == 'blaxel.openai.model'and the single__init__.pyline-3 frame.Fix
Expand
_is_optional_dependency_errorto also treat as expected (and therefore not report):blaxel.langgraph,blaxel.llamaindex,blaxel.openai,blaxel.crewai,blaxel.googleadk,blaxel.livekit,blaxel.pydantic,blaxel.telemetry), andagents,livekit).Genuine SDK import bugs (failures on
blaxel.*core modules) are still captured.Validation
tests/core/test_sentry.py(8 cases) — all pass.blaxel.core.broken) is still captured.BL_API_KEYcredentials not present in CI sandbox).ruff check+ruff formatclean.Remaining risk
Low. The change only narrows what is sent to Sentry, scoped to
ImportErrorfrom optional integration packages; it does not alter integration behavior or what users see at import time.Fixes SDK-PYTHON-YY
Note
Narrows the Sentry import-error suppression to only known public entrypoints of optional integration packages (via a new
_OPTIONAL_INTEGRATION_ENTRYPOINT_MODULESallowlist), so that deeper internal import failures (e.g.blaxel.pydantic.custom.gemni) are still reported as potential SDK bugs.Written by Mendral for commit adaf2cf.